Technotes

Download

Acrobat file (143K)

Download

ClarisWorks 4 file (22K)

QuickView version

not available yet

TECHNOTE: Porting WinHelp to Apple Guide With Guide Maker

Technote 1072

October 1996

By Don Johnson

Apple Developer Technical Support (DTS)

If you are planning to port WinHelp source files to Apple Guide using the Apple Guide Maker development environment, there are some important issues that you need to address. This Technote discusses what you need to know in order to port your WinHelp files successfully.

The information in Apple Guide Complete, Chapter 8, is still accurate, but may be incomplete. For example, when the Guide Maker conversion program indicates that you have a successful conversion, you may just be, in fact, at the beginning of the process. This Technote provides you with the additional information you need to finish the process.

This Note is addressed to developers, technical writers, and instructional help designers who need to convert WinHelp files to Apple Guide source files.

CONTENTS

Using Guide Maker for Conversion

The only publicly-available tool for converting WinHelp to Apple Guide is Guide Maker, Apple's official development environment for creating guide files. You can find it in the Apple Guide section of the Mac OS SDK. Guide Maker converts the WinHelp source RTF files to Guide Script source RTF. There is some preparation required, however, for this to be successful.

Preparing the WinHelp Source RTF Files

The Guide Maker converter requires the WinHelp source files to be RTF (Rich Text Format) but does not use the XTND for translation (unlike the Guide Maker compiler which does use XTND for RTF and other formats). The converter reads the raw RTF directly and does a pattern match search for various items. This is one of the key problems with the converter because you can have several different variations of raw RTF text that mean the same thing. Unfortunately, the converter can only understand a few of these variations. The "safest" variation is the RTF exported by Microsoft Word 4, which is what all of the test cases were taken from when the converter was written.

If the WinHelp source files are in RTF created by Word 6, there may be problems. Several RTF tags exported by Word 6 aren't understood and cause Guide Maker to crash. If you encounter this problem, convert the Word 6 RTF to an earlier RTF version. This can be done as follows:

  1. Open the Word 6 WinHelp source RTF with Word 6. This will convert the RTF to "normal" Word 6 format.
  2. Using Word 6, save the WinHelp source as Word 5.1.
  3. Using Word 5.1, open the Word 5.1 WinHelp source file.
  4. Using Word 5.1, save the file as RTF.

You can also use Word 4 instead of Word 5.1.

On a Power Macintosh, you need to install the XTND Power Enabler in your Extensions folder. This is required by Guide Maker whether or not you are using any XTND translators. The XTND Power Enabler extension is available on the MAC OS SDK in the Guide Maker folder.

Be sure the WinHelp RTF source file type is 'TEXT'. This allows Guide Maker to open the file for conversion.

Also, refer to some other little "gotchas" on pages 8-3 to 8-4 of Apple Guide: Complete.

Using the Guide Maker Converted Output

The Guide Maker converter outputs its files in RTF. The first thing you should do is convert the RTF to the native format of your favorite word processor or text editor. We do not recommend that you leave the output in RTF.

To convert the Guide Maker output from RTF, you'll need a word processor that understands RTF or a word processor that uses XTND translation for RTF.

Microsoft Word is one example of a word processor that can read the Guide Maker RTF output directly. You can then save the file as "normal" Word format or as "text".

If you elect to use a word processor that requires XTND for translation, then you will need to install XTND and a RTF translator.

Two RTF translators are currently available: one from Claris and one from DATAVIZ. If you have any Claris products installed, then you already have the Claris RTF translator. To be sure, check your Claris folder in your system folder for a file named RTF. That's the file you need.

If you want to use the DATAVIZ translator, be sure to remove the Claris RTF translator from the system folder. The RTF translator from DATAVIZ comes free with the retail version of System 7.5. It is not included on the floppy version, just the CD-ROM version. This translator is installed separately from your system software installation. Users have reported that the DATAVIZ RTF translator is more robust than the Claris version.

Before you save the converted file, be sure it ends with one or more 'return' characters. To be safe, go to the end of each file and enter a few return keys. Save the file in your favorite format or as "text".

Determining If the Translation Was Successful

To determine if your translation is successful, examine the Guide Script output after you have converted it from RTF. You can use a word processor or text editor for examining and editing the files.

If the conversion occurs properly, the resulting files will contain, for example, the following Apple Guide script commands:

<Define Sequence> "Decompressor_Functions"
<Define Panel> 5Panel 34"
<End Panel>
<End Sequence>
<Index> "Decompressor"
<Topic> "Decompressor Functions","Decompressor_Functions"

To find the Guide Script commands, you need to search for the <character.

Steps to Fix the Converted File

Guide Maker does not perform the conversion, however, without a few errors. In the previous example, you need to fix the following the RTF conversion errors by hand:

The DATAVIZ RTF converter errors and fixes:

Error: <Define Panel> 5Panel 34"
The necessary fix: <Define Panel> "Panel 34"

Claris RTF converter errors and fixes:

Error: <Define Panel> Panel 34"
The necessary fix: <Define Panel> "Panel 34"

The string following the <Define Panel> is the name of the panel and must be unique. You may need to invent new panel names when you make the fix.

After Conversion

Running the WinHelp files through the Guide Maker converter is only the first step to making a good Apple Guide file.

Refer to the StepUp Software web site <http://rampages.onramp.net/~stepup/>for the latest information on WinHelp conversion and a description of the complete conversion process.

Summary

Porting WinHelp source files to Apple Guide is, by and large, a straightforward conversion process. However, there some important steps you need to follow which aren't completely documented. This Technote tells you what you need to do in order to perform successful conversions.

Further Reference

The following references provide you with additional information on Apple Guide and the WinHelp conversion process.

Acknowledgments

Thanks to Tom Maremaa, Sunny Singha, Brian McGhie.

Technotes
Previous Technote | Contents | Next Technote